home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / Button.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  11.7 KB  |  382 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Button.java    1.50 98/08/19
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. import java.awt.peer.ButtonPeer;
  18. import java.awt.event.*;
  19. import java.io.ObjectOutputStream;
  20. import java.io.ObjectInputStream;
  21. import java.io.IOException;
  22.  
  23.  
  24. /**
  25.  * This class creates a labeled button. The application can cause
  26.  * some action to happen when the button is pushed. This image
  27.  * depicts three views of a "<code>Quit</code>" button as it appears
  28.  * under the Solaris operating system:
  29.  * <p>
  30.  * <img src="doc-files/Button-1.gif"
  31.  * ALIGN=center HSPACE=10 VSPACE=7>
  32.  * <p>
  33.  * The first view shows the button as it appears normally.
  34.  * The second view shows the button
  35.  * when it has input focus. Its outline is darkened to let the
  36.  * user know that it is an active object. The third view shows the
  37.  * button when the user clicks the mouse over the button, and thus
  38.  * requests that an action be performed.
  39.  * <p>
  40.  * The gesture of clicking on a button with the mouse
  41.  * is associated with one instance of <code>ActionEvent</code>,
  42.  * which is sent out when the mouse is both pressed and released
  43.  * over the button. If an application is interested in knowing
  44.  * when the button has been pressed but not released, as a separate
  45.  * gesture, it can specialize <code>processMouseEvent</code>,
  46.  * or it can register itself as a listener for mouse events by
  47.  * calling <code>addMouseListener</code>. Both of these methods are
  48.  * defined by <code>Component</code>, the abstract superclass of
  49.  * all components.
  50.  * <p>
  51.  * When a button is pressed and released, AWT sends an instance
  52.  * of <code>ActionEvent</code> to the button, by calling
  53.  * <code>processEvent</code> on the button. The button's
  54.  * <code>processEvent</code> method receives all events
  55.  * for the button; it passes an action event along by
  56.  * calling its own <code>processActionEvent</code> method.
  57.  * The latter method passes the action event on to any action
  58.  * listeners that have registered an interest in action
  59.  * events generated by this button.
  60.  * <p>
  61.  * If an application wants to perform some action based on
  62.  * a button being pressed and released, it should implement
  63.  * <code>ActionListener</code> and register the new listener
  64.  * to receive events from this button, by calling the button's
  65.  * <code>addActionListener</code> method. The application can
  66.  * make use of the button's action command as a messaging protocol.
  67.  *
  68.  * @version     1.50 08/19/98
  69.  * @author     Sami Shaio
  70.  * @see         java.awt.event.ActionEvent
  71.  * @see         java.awt.event.ActionListener
  72.  * @see         java.awt.Component#processMouseEvent
  73.  * @see         java.awt.Component#addMouseListener
  74.  * @since       JDK1.0
  75.  */
  76. public class Button extends Component {
  77.  
  78.     /*
  79.     * The button's Label.
  80.     * If Label is not specified it will default to "".
  81.     * @serial
  82.     * @see getLabel()
  83.     * @see setLabel()
  84.     */
  85.     String label;
  86.     /*
  87.     * The action to be performaed once a button has been
  88.     * pressed.
  89.     * actionCommand can be null. 
  90.     * @serial
  91.     * @see getActionCommand()
  92.     * @see setActionCommand()
  93.     */
  94.     String actionCommand;
  95.  
  96.     transient ActionListener actionListener;
  97.  
  98.     private static final String base = "button";
  99.     private static int nameCounter = 0;
  100.  
  101.     /*
  102.      * JDK 1.1 serialVersionUID
  103.      */
  104.     private static final long serialVersionUID = -8774683716313001058L;
  105.  
  106.  
  107.     static {
  108.         /* ensure that the necessary native libraries are loaded */
  109.     Toolkit.loadLibraries();
  110.     initIDs();
  111.     }
  112.  
  113.     /**
  114.      * Initialize JNI field and method IDs for fields that may be
  115.        accessed from C.
  116.      */
  117.     private static native void initIDs();
  118.  
  119.     /**
  120.      * Constructs a Button with no label.
  121.      */
  122.     public Button() {
  123.     this("");
  124.     }
  125.  
  126.     /**
  127.      * Constructs a Button with the specified label.
  128.      * @param label A string label for the button.
  129.      */
  130.     public Button(String label) {
  131.     this.label = label;
  132.     }
  133.  
  134.     /**
  135.      * Construct a name for this component.  Called by getName() when the
  136.      * name is null.
  137.      */
  138.     String constructComponentName() {
  139.         synchronized (getClass()) {
  140.         return base + nameCounter++;
  141.     }
  142.     }
  143.  
  144.     /**
  145.      * Creates the peer of the button.  The button's peer allows the
  146.      * application to change the look of the button without changing
  147.      * its functionality.
  148.      * @see     java.awt.Toolkit#createButton(java.awt.Button)
  149.      * @see     java.awt.Component#getToolkit()
  150.      */
  151.     public void addNotify() {
  152.         synchronized(getTreeLock()) {
  153.         if (peer == null) 
  154.             peer = getToolkit().createButton(this);
  155.         super.addNotify();
  156.     }
  157.     }
  158.  
  159.     /**
  160.      * Gets the label of this button.
  161.      * @return    the button's label, or <code>null</code>
  162.      *                if the button has no label.
  163.      * @see       java.awt.Button#setLabel
  164.      */
  165.     public String getLabel() {
  166.     return label;
  167.     }
  168.  
  169.     /**
  170.      * Sets the button's label to be the specified string.
  171.      * @param     label   the new label, or <code>null</code>
  172.      *                if the button has no label.
  173.      * @see       java.awt.Button#getLabel
  174.      */
  175.     public void setLabel(String label) {
  176.         boolean testvalid = false;
  177.  
  178.     synchronized (this) {
  179.         if (label != this.label && (this.label == null ||
  180.                     !this.label.equals(label))) {
  181.             this.label = label;
  182.         ButtonPeer peer = (ButtonPeer)this.peer;
  183.         if (peer != null) {
  184.             peer.setLabel(label);
  185.         }
  186.         testvalid = true;
  187.         }
  188.     }
  189.  
  190.     // This could change the preferred size of the Component.
  191.     if (testvalid && valid) {
  192.         invalidate();
  193.     }
  194.     }
  195.  
  196.     /**
  197.      * Sets the command name for the action event fired
  198.      * by this button. By default this action command is
  199.      * set to match the label of the button.
  200.      * @param     command  A string used to set the button's
  201.      *                  action command.
  202.      *            If the string is <code>null</code> then the action command
  203.      *            is set to match the label of the button.
  204.      * @see       java.awt.event.ActionEvent
  205.      * @since     JDK1.1
  206.      */
  207.     public void setActionCommand(String command) {
  208.         actionCommand = command;
  209.     }
  210.  
  211.     /**
  212.      * Returns the command name of the action event fired by this button.
  213.      * If the command name is <code>null</code> (default) then this method
  214.      * returns the label of the button.
  215.      */
  216.     public String getActionCommand() {
  217.         return (actionCommand == null? label : actionCommand);
  218.     }
  219.  
  220.     /**
  221.      * Adds the specified action listener to receive action events from
  222.      * this button. Action events occur when a user presses or releases
  223.      * the mouse over this button.
  224.      * If l is null, no exception is thrown and no action is performed.
  225.      *
  226.      * @param         l the action listener
  227.      * @see           java.awt.event.ActionListener
  228.      * @see           java.awt.Button#removeActionListener
  229.      * @since         JDK1.1
  230.      */
  231.     public synchronized void addActionListener(ActionListener l) {
  232.     if (l == null) {
  233.         return;
  234.     }
  235.     actionListener = AWTEventMulticaster.add(actionListener, l);
  236.         newEventsOnly = true;
  237.     }
  238.  
  239.     /**
  240.      * Removes the specified action listener so that it no longer
  241.      * receives action events from this button. Action events occur
  242.      * when a user presses or releases the mouse over this button.
  243.      * If l is null, no exception is thrown and no action is performed.
  244.      *
  245.      * @param             l     the action listener
  246.      * @see               java.awt.event.ActionListener
  247.      * @see               java.awt.Button#addActionListener
  248.      * @since             JDK1.1
  249.      */
  250.     public synchronized void removeActionListener(ActionListener l) {
  251.     if (l == null) {
  252.         return;
  253.     }
  254.     actionListener = AWTEventMulticaster.remove(actionListener, l);
  255.     }
  256.  
  257.     // REMIND: remove when filtering is done at lower level
  258.     boolean eventEnabled(AWTEvent e) {
  259.         if (e.id == ActionEvent.ACTION_PERFORMED) {
  260.             if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 ||
  261.                 actionListener != null) {
  262.                 return true;
  263.             }
  264.             return false;
  265.         }
  266.         return super.eventEnabled(e);
  267.     }
  268.  
  269.     /**
  270.      * Processes events on this button. If an event is
  271.      * an instance of <code>ActionEvent</code>, this method invokes
  272.      * the <code>processActionEvent</code> method. Otherwise,
  273.      * it invokes <code>processEvent</code> on the superclass.
  274.      * @param        e the event.
  275.      * @see          java.awt.event.ActionEvent
  276.      * @see          java.awt.Button#processActionEvent
  277.      * @since        JDK1.1
  278.      */
  279.     protected void processEvent(AWTEvent e) {
  280.         if (e instanceof ActionEvent) {
  281.             processActionEvent((ActionEvent)e);
  282.             return;
  283.         }
  284.     super.processEvent(e);
  285.     }
  286.  
  287.     /**
  288.      * Processes action events occurring on this button
  289.      * by dispatching them to any registered
  290.      * <code>ActionListener</code> objects.
  291.      * <p>
  292.      * This method is not called unless action events are
  293.      * enabled for this button. Action events are enabled
  294.      * when one of the following occurs:
  295.      * <p><ul>
  296.      * <li>An <code>ActionListener</code> object is registered
  297.      * via <code>addActionListener</code>.
  298.      * <li>Action events are enabled via <code>enableEvents</code>.
  299.      * </ul>
  300.      * @param       e the action event.
  301.      * @see         java.awt.event.ActionListener
  302.      * @see         java.awt.Button#addActionListener
  303.      * @see         java.awt.Component#enableEvents
  304.      * @since       JDK1.1
  305.      */
  306.     protected void processActionEvent(ActionEvent e) {
  307.         if (actionListener != null) {
  308.             actionListener.actionPerformed(e);
  309.         }
  310.     }
  311.  
  312.     /**
  313.      * Returns the parameter string representing the state of this
  314.      * button. This string is useful for debugging.
  315.      * @return     the parameter string of this button.
  316.      */
  317.     protected String paramString() {
  318.     return super.paramString() + ",label=" + label;
  319.     }
  320.  
  321.  
  322.     /* Serialization support.
  323.      */
  324.     /*
  325.     * Button Serial Data Version.
  326.     * @serial
  327.     */
  328.     private int buttonSerializedDataVersion = 1;
  329.  
  330.     /**
  331.     * Writes default serializable fields to stream.  Writes
  332.     * a list of serializable ItemListener(s) as optional data.
  333.     * The non-serializable ItemListner(s) are detected and 
  334.     * no attempt is made to serialize them.
  335.     *
  336.     * @serialData Null terminated sequence of 0 or more pairs.
  337.     *              The pair consists of a String and Object.
  338.     *              The String indicates the type of object and
  339.     *               is one of the following :
  340.     *              itemListenerK indicating and ItemListener object.
  341.     *             
  342.     * @see AWTEventMulticaster.save(ObjectOutputStream, String, EventListener)
  343.     * @see java.awt.Component.itemListenerK
  344.     */
  345.     private void writeObject(ObjectOutputStream s)
  346.       throws IOException
  347.     {
  348.       s.defaultWriteObject();
  349.  
  350.       AWTEventMulticaster.save(s, actionListenerK, actionListener);
  351.       s.writeObject(null);
  352.     }
  353.  
  354.     /*
  355.     * Read the ObjectInputStream and if it isnt null
  356.     * add a listener to receive item events fired
  357.     * by the button.
  358.     * Unrecognised keys or values will be Ignored.
  359.     * @serial
  360.     * @see removeActionListener()
  361.     * @see addActionListener()
  362.     */
  363.  
  364.     private void readObject(ObjectInputStream s)
  365.       throws ClassNotFoundException, IOException
  366.     {
  367.       s.defaultReadObject();
  368.  
  369.       Object keyOrNull;
  370.       while(null != (keyOrNull = s.readObject())) {
  371.     String key = ((String)keyOrNull).intern();
  372.  
  373.     if (actionListenerK == key)
  374.       addActionListener((ActionListener)(s.readObject()));
  375.  
  376.     else // skip value for unrecognized key
  377.       s.readObject();
  378.       }
  379.     }
  380.  
  381. }
  382.